<!DOCTYPE html>
<html lang="en">
  <head>
    <title>CryptorECC  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
  </head>
  <body>
    <a title="CryptorECC  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">CryptorECC Docs</a> (100% documented)</p>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">CryptorECC Reference</a>
        <img id="carat" src="img/carat.png" />
        CryptorECC  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/ECPrivateKey.html">ECPrivateKey</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/ECPublicKey.html">ECPublicKey</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Extensions/Data.html">Data</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/String.html">String</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/ECError.html">ECError</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/ECSignature.html">ECSignature</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/EllipticCurve.html">EllipticCurve</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <p align="center">
    <a href="http://kitura.io/">
        <img src="https://raw.githubusercontent.com/IBM-Swift/Kitura/master/Sources/Kitura/resources/kitura-bird.svg?sanitize=true" height="100" alt="Kitura">
    </a>
</p>

<p align="center">
    <a href="https://ibm-swift.github.io/BlueECC/index.html">
    <img src="https://img.shields.io/badge/apidoc-BlueECC-1FBCE4.svg?style=flat" alt="APIDoc">
    </a>
    <a href="https://travis-ci.org/IBM-Swift/BlueECC">
    <img src="https://travis-ci.org/IBM-Swift/BlueECC.svg?branch=master" alt="Build Status - Master">
    </a>
    <img src="https://img.shields.io/badge/os-macOS-green.svg?style=flat" alt="macOS">
    <img src="https://img.shields.io/badge/os-linux-green.svg?style=flat" alt="Linux">
    <img src="https://img.shields.io/badge/license-Apache2-blue.svg?style=flat" alt="Apache 2">
    <a href="http://swift-at-ibm-slack.mybluemix.net/">
    <img src="http://swift-at-ibm-slack.mybluemix.net/badge.svg" alt="Slack Status">
    </a>
</p>
<h1 id='blueecc' class='heading'>BlueECC</h1>

<p>A cross platform Swift implementation of Elliptic Curve Digital Signature Algorithm (ECDSA) and Elliptic Curve Integrated Encryption Scheme (ECIES). This allows you to sign, verify, encrypt and decrypt using elliptic curve keys.</p>
<h2 id='swift-version' class='heading'>Swift version</h2>

<p>The latest version of BlueECC requires <strong>Swift 4.1</strong> or later. You can download this version of the Swift binaries by following this <a href="https://swift.org/download/">link</a>. Compatibility with other Swift versions is not guaranteed.</p>
<h2 id='usage' class='heading'>Usage</h2>
<h4 id='add-dependencies' class='heading'>Add dependencies</h4>

<p>Add the <code>BlueECC</code> package to the dependencies within your application’s <code>Package.swift</code> file. Substitute <code>&quot;x.x.x&quot;</code> with the latest <code>BlueECC</code> <a href="https://github.com/IBM-Swift/BlueECC/releases">release</a>.</p>
<pre class="highlight swift"><code><span class="o">.</span><span class="nf">package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/IBM-Swift/BlueECC.git"</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="s">"x.x.x"</span><span class="p">)</span>
</code></pre>

<p>Add <code>CryptorECC</code> to your target&rsquo;s dependencies:</p>
<pre class="highlight swift"><code><span class="o">.</span><span class="nf">target</span><span class="p">(</span><span class="nv">name</span><span class="p">:</span> <span class="s">"example"</span><span class="p">,</span> <span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span><span class="s">"CryptorECC"</span><span class="p">]),</span>
</code></pre>
<h4 id='import-package' class='heading'>Import package</h4>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">CryptorECC</span>
</code></pre>
<h3 id='getting-started' class='heading'>Getting Started</h3>
<h4 id='elliptic-curve-private-key' class='heading'>Elliptic curve private key</h4>

<p>you can generate an ECPrivate key using BlueECC.</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">p256PrivateKey</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">ECPrivateKey</span><span class="o">.</span><span class="nf">make</span><span class="p">(</span><span class="nv">for</span><span class="p">:</span> <span class="o">.</span><span class="n">prime256v1</span><span class="p">)</span>
</code></pre>

<p>You can then view the key in it&rsquo;s PEM format as follows:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">privateKeyPEM</span> <span class="o">=</span> <span class="n">p256PrivateKey</span><span class="o">.</span><span class="n">pemString</span>
</code></pre>

<p>The following curves are supported:</p>

<ul>
<li>prime256v1</li>
<li>secp384r1</li>
<li>secp521r1</li>
</ul>

<p>Alternatively, you may generate private key using a third party provider:</p>

<ul>
<li><p>You can generate a <code>p-256</code> private key as a <code>.p8</code> file for Apple services from <a href="https://developer.apple.com/account/ios/authkey/">https://developer.apple.com/account/ios/authkey</a>. This will produce a key that should be formatted as follows:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">privateKey</span> <span class="o">=</span>
<span class="s">"""
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQglf7ztYnsaHX2yiHJ
meHFl5dg05y4a/hD7wwuB7hSRpmhRANCAASKRzmboLbG0NZ54B5PXxYSU7fvO8U7
PyniQCWG+Agc3bdcgKU0RKApWYuBJKrZqyqLB2tTlgdtwcWSB0AEzVI8
-----END PRIVATE KEY-----
"""</span>
</code></pre></li>
<li><p>You can use OpenSSL <a href="https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations">Command Line Elliptic Curve Operations</a>.  </p></li>
</ul>

<p>The following commands generate private keys for the three supported curves as <code>.pem</code> files:</p>
<pre class="highlight plaintext"><code>// p-256
$ openssl ecparam -name prime256v1 -genkey -noout -out key.pem
// p-384
$ openssl ecparam -name secp384r1 -genkey -noout -out key.pem
// p-521
$ openssl ecparam -name secp521r1 -genkey -noout -out key.pem
</code></pre>

<p>These keys will be formatted as follows:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">privateKey</span> <span class="o">=</span>
<span class="s">"""
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIJX+87WJ7Gh19sohyZnhxZeXYNOcuGv4Q+8MLge4UkaZoAoGCCqGSM49
AwEHoUQDQgAEikc5m6C2xtDWeeAeT18WElO37zvFOz8p4kAlhvgIHN23XIClNESg
KVmLgSSq2asqiwdrU5YHbcHFkgdABM1SPA==
-----END EC PRIVATE KEY-----
"""</span>
</code></pre>

<p>The key string can then be used to initialize an <code><a href="Classes/ECPrivateKey.html">ECPrivateKey</a></code> instance:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">eccPrivateKey</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">ECPrivateKey</span><span class="p">(</span><span class="nv">key</span><span class="p">:</span> <span class="n">privateKey</span><span class="p">)</span>
</code></pre>
<h4 id='elliptic-curve-public-key' class='heading'>Elliptic curve public  key</h4>

<p>You can use OpenSSL to generate an elliptic curve public key <code>.pem</code> file from any of the above elliptic curve private key files:</p>
<pre class="highlight plaintext"><code>$ openssl ec -in key.pem -pubout -out public.pem
</code></pre>

<p>This will produce a public key formatted as follows:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">publicKey</span> <span class="o">=</span>
<span class="s">"""
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEikc5m6C2xtDWeeAeT18WElO37zvF
Oz8p4kAlhvgIHN23XIClNESgKVmLgSSq2asqiwdrU5YHbcHFkgdABM1SPA==
-----END PUBLIC KEY-----
"""</span>
</code></pre>

<p>These keys can then be used to initialize an <code><a href="Classes/ECPrivateKey.html">ECPrivateKey</a></code> instance:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">eccPublicKey</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">ECPublicKey</span><span class="p">(</span><span class="nv">key</span><span class="p">:</span> <span class="n">publicKey</span><span class="p">)</span>
</code></pre>

<p>Alternatively, you can extract the public key from your <code><a href="Classes/ECPrivateKey.html">ECPrivateKey</a></code>:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">eccPublicKey</span> <span class="o">=</span> <span class="k">try</span> <span class="n">eccPrivateKey</span><span class="o">.</span><span class="nf">extractPublicKey</span><span class="p">()</span>
<span class="nf">print</span><span class="p">(</span><span class="n">eccPublicKey</span><span class="o">.</span><span class="n">pemString</span><span class="p">)</span>
</code></pre>
<h4 id='signing-string-or-data' class='heading'>Signing String or Data</h4>

<p>BlueECC extends <code>String</code> and <code>Data</code> so you can call sign directly on your plaintext using an EC private key. This creates an <code><a href="Structs/ECSignature.html">ECSignature</a></code> containing the r and s signature values:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">message</span> <span class="o">=</span> <span class="s">"hello world"</span>
<span class="k">let</span> <span class="nv">signature</span> <span class="o">=</span> <span class="k">try</span> <span class="n">message</span><span class="o">.</span><span class="nf">sign</span><span class="p">(</span><span class="nv">with</span><span class="p">:</span> <span class="n">eccPrivateKey</span><span class="p">)</span>
</code></pre>
<h4 id='verifying-the-signature' class='heading'>Verifying the signature</h4>

<p>Use the public key to verify the signature for the plaintext:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">verified</span> <span class="o">=</span> <span class="n">signature</span><span class="o">.</span><span class="nf">verify</span><span class="p">(</span><span class="nv">plaintext</span><span class="p">:</span> <span class="n">message</span><span class="p">,</span> <span class="nv">using</span><span class="p">:</span> <span class="n">eccPublicKey</span><span class="p">)</span>
<span class="k">if</span> <span class="n">verified</span> <span class="p">{</span>
    <span class="nf">print</span><span class="p">(</span><span class="s">"Signature is valid for provided plaintext"</span><span class="p">)</span>
<span class="p">}</span>
</code></pre>
<h4 id='encrypting-string-or-data' class='heading'>Encrypting String or Data</h4>

<p>Use the public key to encrypt your plaintext String or Data to encrypted Data or an encrypted Base64Encoded String:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">encryptedData</span> <span class="o">=</span> <span class="k">try</span> <span class="s">"Hello World"</span><span class="o">.</span><span class="nf">encrypt</span><span class="p">(</span><span class="nv">with</span><span class="p">:</span> <span class="n">eccPublicKey</span><span class="p">)</span>
<span class="nf">print</span><span class="p">(</span><span class="n">encryptedData</span><span class="o">.</span><span class="nf">base64EncodedString</span><span class="p">())</span>
</code></pre>
<h4 id='decrypting-to-plaintext' class='heading'>Decrypting to plaintext</h4>

<p>Use the private key to decrypt the encrypted Data or Base64Encoded String to plaintext Data or UTF8 String:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">decryptedData</span> <span class="o">=</span> <span class="k">try</span> <span class="n">encryptedData</span><span class="o">.</span><span class="nf">decrypt</span><span class="p">(</span><span class="nv">with</span><span class="p">:</span> <span class="n">eccPrivateKey</span><span class="p">)</span>
<span class="nf">print</span><span class="p">(</span><span class="kt">String</span><span class="p">(</span><span class="nv">data</span><span class="p">:</span> <span class="n">decryptedData</span><span class="p">,</span> <span class="nv">encoding</span><span class="p">:</span> <span class="o">.</span><span class="n">utf8</span><span class="p">))</span>
</code></pre>
<h4 id='encryption-interoperability' class='heading'>Encryption interoperability</h4>

<p>Cross platform encryption and decryption is currently only supported with <code>prime256v1</code> curves. The <code>secp384r1</code> and <code>secp521r1</code> curves do not support Linux encryption with Apple platform decryption and vice versa.</p>

<p>If you would like to interoperate with this repo,
The following describes the encryption process:</p>

<ul>
<li>Generate an ephemeral EC key pair</li>
<li>Use ECDH of your EC pair to generate a symmetric key</li>
<li>Use SHA256 ANSI x9.63 Key Derivation Function with the ephemeral public key to generate a 32 byte key</li>
<li>Use the first 16 bytes as an AES-GCM key</li>
<li>Use the second 16 bytes as the initialization vector (IV)</li>
<li>Use aes_128_gcm to encrypt the plaintext and generate a 16 byte GCM tag</li>
<li>Send the ephemeral public key, encrypted data and GCM tag</li>
</ul>

<p>This is equivalent to: <code>kSecKeyAlgorithmECIESEncryptionStandardVariableIVX963SHA256AESGCM</code> when using apple security.  </p>
<h2 id='api-documentation' class='heading'>API Documentation</h2>

<p>For more information visit our <a href="https://ibm-swift.github.io/BlueECC/index.html">API reference</a>.</p>
<h2 id='community' class='heading'>Community</h2>

<p>We love to talk server-side Swift, and Kitura. Join our <a href="http://swift-at-ibm-slack.mybluemix.net/">Slack</a> to meet the team!</p>
<h2 id='license' class='heading'>License</h2>

<p>This library is licensed under Apache 2.0. Full license text is available in <a href="https://github.com/IBM-Swift/BlueECC/blob/master/LICENSE.txt">LICENSE</a>.</p>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2019 <a class="link" href="https://github.com/IBM-Swift/BlueECC" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2019-03-12)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.1</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</div>
</html>
